Skip to content

LUS .meta alias rework testing - #6977

Draft
briaguya0 wants to merge 11 commits into
HarbourMasters:developfrom
briaguya0:meta-alias-testing
Draft

LUS .meta alias rework testing#6977
briaguya0 wants to merge 11 commits into
HarbourMasters:developfrom
briaguya0:meta-alias-testing

Conversation

@briaguya0

@briaguya0 briaguya0 commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Testing PR for:

Not for merge — this is a manual test kit (under meta-alias-testing/) plus a libultraship
submodule bump to the branch in that PR, so the .meta alias rework can be exercised in a real
game.

How it works

It aliases the boot ship-logo DisplayList (gShipLogoDL, the first logo shown at startup) via
a .meta, and recolors the assets so the loaded one is obvious at a glance:

color meaning
brown soh.o2r's own (vanilla) gShipLogoDL — always the lowest-priority provider
green a mod's real gShipLogoDL
magenta the alias target (fancyShipDL.xml)

Drop a case's .o2r(s) into mods/, boot, and read the first logo's color (press A/B/Start to skip
past the logos). See meta-alias-testing/README.md
for the full legend, run/priority steps, and the resolution model, and
meta-alias-testing/meta-loading.md
for the flowchart.

Coverage

  • Single-mod (o2r/case*.o2r): alias target present → target, target absent → fallback to the
    real, meta-only, and a no-.meta regression check.
  • Layered / archive priority (o2r/layered/): the cross-game flagship (a .meta below a
    real whose target lives higher → the alias wins; drop the target mod → vanilla), L1 (a real
    above the alias target → the real wins), and reach-back (the target lives below the .meta
    still resolves).

Results

meta-alias-testing/BASELINE.md (stock engine) and meta-alias-testing/STATUS.md (with the fix)
record the before/after. Every case matches the model, with five flips proving the fix:
case1 / case3 / flagship / reach-back → magenta, and case4 → brown (no more shadowing).

🤖 Generated with Claude Code

Build Artifacts

briaguya0 and others added 10 commits July 23, 2026 23:31
Testing branch scaffolding for the libultraship .meta alias fallback work
(Kenix3/libultraship#1165, which also needs the HarbourMasters#984 .meta resolution fix).

Expands the manual test from HarbourMasters/Shipwright@f5d2e58: a .meta file
aliases the boot ship logo DisplayList to a renamed copy, and we watch the
title screen to see which asset loaded. This kit covers the full real/meta/
target matrix as five committed mod .o2r files, and recolors the assets
(default = green, replacement = magenta) so the loaded one is obvious.

- meta-alias-testing/README.md   test matrix, run steps, color legend
- meta-alias-testing/PLAN.md      implementation + test plan
- regen-assets.sh / build-o2r.sh  reproduce the assets and archives
- o2r/case{1..5}-*.o2r            the five committed test archives
- .gitignore                      re-include the *.o2r / *.meta fixtures
- README.md                       note the testing branch + link the kit

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
All five test cases plus the no-mod control observed on the unmodified
libultraship submodule (2bfbde3a); results match predictions. .meta aliases
are confirmed non-functional today: ignored when a real asset exists (cases
1/2 load green, not magenta), unresolvable when it doesn't (cases 3/4 blank).
The fix must flip case1 green->magenta and case3 nothing->magenta.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Bumps the libultraship pointer to the change-#1 commit (index .meta under its
literal name) and records results in STATUS.md.

Observed vs baseline:
- case1 green -> magenta (alias now resolves once the .meta is indexed)
- case2 green -> nothing (expected temporary regression; no fallback until #3)
- case3/4 nothing, case5 green (unchanged)

Note: reproducing this branch's submodule state needs the meta-alias-fallback
branch pushed to the fork (remote `briaguya`).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Bumps libultraship to the fallback commit (ResourceLoader::LoadResource prefers
target, else falls back to the real asset) and records results.

Observed: case2 nothing -> green (fallback restored); case1 magenta, case3/4
nothing, case5 green (unchanged). Relabels STATUS.md columns to application
order (index, fallback, reachability).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The single-archive cases missed the multi-archive behavior the issues require
(libultraship HarbourMasters#1165's design notes + HarbourMasters#984). Add layered .o2r sets and document
the full resolution model.

New layered sets (o2r/layered/, 20-* = higher priority):
- L1  higher real must beat lower .meta   -> green  (exposes the current bug: magenta)
- L1b higher real over lower meta-only     -> green
- L2  higher .meta beats lower real        -> magenta
- L3  higher meta-only over lower real     -> nothing (fallback is same-archive only)
- L5  cross-game motivation: base ships alias+native real, separate mod supplies
      the shared target; toggle -> magenta ("mod loaded") / green ("vanilla")
- L6  "reach back": winning .meta resolves its target from a separate archive

README now documents the resolution model: resource/resource.meta are one
override identity by priority; the winner decides; the alias target resolves
globally (any archive); the same-path fallback is winner-local only (L3); else
fail. build-o2r.sh is now deterministic (fixed timestamps).

Known gap this documents: the current engine changes fail L1 (separate override
identities) — motivates the override-identity rework.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Mermaid diagrams of the intended .meta resolution model: winner selection by
archive priority, the .meta alias/fallback decision, and the target-global vs
same-path-fallback-winner-local asymmetry. Maps each leaf to the test cases and
notes where it lands in the code. Mermaid so it renders on GitHub and can be
ported into the LUS doxygen docs later. Linked from README's resolution model.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The winner-owns-identity model gave the wrong answer for the flagship
cross-game case (a lower-priority .meta whose target lives in a higher archive
should win). Corrected model: X.meta -> Y adds Y as an alternate provider of X,
ranked by the archive where its asset lives (not where the .meta lives); the
request loads the highest-priority provider (real X or aliased Y). This yields
both the flagship (alias wins) and the L1 edge (higher real wins) from one rule;
"fallback" is just the case where the target doesn't exist.

- meta-loading.md: new flowchart + worked examples (flagship A/B and L1).
- README: resolution-model section replaced with the provider rule; a warning
  notes the per-case tables are being recomputed against it (next step).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Rebuild the case set around meta-loading.md (provider ranking), replacing the
shadowing-based layered sets:

- Single-mod case1-5 unchanged in content; case4 expected flips nothing -> brown
  (no shadowing — soh.o2r's real gShipLogoDL is always the lowest provider).
- Layered sets replaced with:
  - flagship-* : 3 mods (meta / real / target) replicating 2ship / mm / mod;
    all three -> magenta, drop the target -> green (the vanilla toggle).
  - L1-*       : real above the alias target -> real wins.
  - reachback-*: alias target below the .meta -> still resolves.
- README: color legend (brown = soh's vanilla real, a real result), case tables,
  layered docs, run/priority steps rewritten to the model.
- BASELINE.md / STATUS.md moved to historical/ (old shadowing model); fresh ones
  to be recorded after the override-identity rework.

o2r builds are deterministic, so equal building blocks show up as renames.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…bfbde3a)

Baseline of the reworked test kit against the unmodified engine (2bfbde3a =
develop's pin). All observations matched predictions:
- real+meta cases load the mod's plain real, .meta ignored (green): case1/2/5,
  flagship, L1
- meta-only cases shadow soh's real but can't resolve (blank): case3/4, reachback

Resets the submodule pointer from the earlier engine-change commits back to
develop so the branch reflects the stock engine this baseline was taken on. The
override-identity rework and a fresh STATUS.md come next.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Bumps libultraship to the meta-provider-resolution commit and records STATUS.md:
all 10 cases (control + 5 single + 4 layered) match the expected after-fix
results, with five flips proving the fix (case1/case3/flagship/reachback ->
magenta, case4 -> brown).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@serprex serprex added the do not merge Not ready or not valid changes label Jul 24, 2026
@Jameriquiah

Jameriquiah commented Jul 24, 2026

Copy link
Copy Markdown
Member
image

some testing trying to load a gLinkHumanSkel over gLinkChildSkel. eye textures load but are oddly distorted, not sure why considering both are the same texture format and resolution as vanilla. gLinkFierceDeitySkel over gLinkAdultSkel is just giving me crashes i cannot figure out why, and it appears with meta usage Player_IsCustomLinkModel is not getting hit in z_player_lib.c so the waist DL doesn't load properly

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

do not merge Not ready or not valid changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants